home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Inside Mac Games Volume 7 #1
/
IMG Vol 7-1.iso
/
Updaters
/
InputSprocket 1.3
/
InputSprocket Developer Notes
next >
Wrap
Text File
|
1998-04-16
|
21KB
|
459 lines
InputSprocket 1.3
Release Notes
-------------------
General Release Notes:
Although not a change, a clarification is needed on how exclusive items operate
particularly with regards to hat-type switches (direction-pads, digital
joysticks and hat switches). A group of mutually exclusive items is a group of
items where activation of one item automatically deactivates other items in the
group. A group of mutually exclusive items might be assigned to a hat. An
example is "look" functionality which allows the user to different directions
from the cockpit in a flight simulator implemented as four different button
needs. A problem will arise if the group of items only uses the activation of
these buttons to select which item is active. This problem will only arise if
the program in question does not properly handle combinations of the button
activations.
For example, if I assign "look right" to the right item of a hat and "look
forward" to the top item of a hat. Now, if I press right on the hat I will look
right. If I now wiggle my thumb upwards so that up is activated (up and right
are now simultaneously activated) I will look forward. If I slide my thumb back
to the right, I will release the "look up" item, but since the "look right"
item was activated the whole time, I do not reactivate the "look right"
function. I now have my thumb holding the hat right, but I am looking forward.
In fact, since the "look right" item is already held down, it is the ONLY
button on the entire controller which cannot be pressed and it becomes
impossible to look right without releasing the hat and pressing it right again.
Symptoms of this are that it is easier to look right by pressing forward and
sliding right to the corner of the d-pad than it is to press right directly!
The only way to correct for this is to consider both presses (kISpButtonDown)
and releases (kISpButtonUp) of any button needs which are exclusive. In this
case, when right is pressed, the right function would be activated. When the up
function is activated, both items are now activated. The InputSprocket client
can either deactivate the original right function and switch to the up
function, or it can remain with the right function and only switch to the up
function when the right button is released. If the hat is moved to the right
again and the up function is released, then the client should switch back to
the right function if it has switched away.
Proper handling of releases for button needs will allow mutually exclusive
functions to operate properly.
Before you ship any application, check to make sure you get no warnings when
running with InputSprocketDebugLib and the debug versions of the drivers.
Changes from 1.2
-----------------
A resource definition file "InputSprocket.r" has been added. You can use this
file to create a Rez '.r' file to build the ISp resources into your
application.
One of the templates is for the 'tset' resource created by the ISp keyboard
driver. Note this templete is ONLY valid for a 'tset' generated by the
keyboard. The only way to tell who created the 'tset' is to examine the 'setl'
resource that points to it. The new sample code for DroneZone uses this
template so that the defaults for the keyboard are in a Rez file and are
easily updated when then application's list of needs changes. You still have
recreate the sets for mice and gaming devices when your needs list changes
during development, but not having to re-setup all the keyboard keys every
time should be a big win. (Note: You may have to delete your InputSprocket
Preferences file in order to get the new defaults from the application -- or
change the subCreatorCode passed to ISpInit.)
New drivers have been added:
InputSprocket CH Trackball: support for CH Trackballs
InputSprocket Contour: support for the Contour Mouse
InputSprocket MicroSpeed: support for MacTRAC and MouseDeluxe
InputSprocket NoHands: support for the NoHands mouse
InputSprocket ArenaMouse: support for the 'Arena' 3D mouse
InputSprocket MacALLY: support for the MacALLY Joystick
InputSprocket USB: support for some USB devices on a Mac with USB
Special thanks to Jeremy Erwin who is not affiliated with MacALLY, for the
code to support the MacALLY stick.
In the debug folder, there is a new driver:
InputSprocket NeedView: useful for debugging your application
All mice and keyboard drivers are 'passthru' in the debug versions. This
means that it is VERY important you make sure you also test with the release
versions of the drivers, since some things will work fine with the debug
versions but not with the release drivers. On the other hand, you will never
get stuck in the debugger without being able to type and/or move the cursor.
InputSprocket resets all elements to 'zero' values (symmetric axis are
reset to the center) across suspend/resume. It is the responsibility of
individual ISp drivers to push data to any elements which are non-default
valued when the driver is reactivated.
ISp drivers must insure that they are Virtual Memory (VM) safe.
InterruptTickle is only called at 'VM safe' times. However, ISp drivers must
be aware of any callbacks they install directly, and whether they can occur
during 'VM unsafe' times. If so then the ISp Driver is responsible for
insuring that it is memory resident. Drivers which use ADB can include
InputSprocketDefer.h and link to InputSprocketDeferLib which provides services
so that ADB handlers are deferred until paging safe time. This way, the driver
does not have to be held (although it will be resident under most conditions
if it is actually being called many times a second). Drivers which use USB
via USBHIDUniversalModule will automatically be deferred until 'VM safe'
times, so do not have to worry about this problem.
Many minor bugs have been fixed.
68K support has been added. 68K InputSprocket is only available through
CFM-68K.
Some new constants were added to InputSprocket.h.
InputSprocket 1.2
Release Notes
-----------------
General Release Notes:
This release involves many minor improvements to the InputSprocket drivers,
including an improved user interface (UI) for axis. Some new drivers have
also been added. Several problems and bugs have been addressed.
A new resource has been defined (kISpApplicationResourceType = 'isap') which
all
applications which use InputSprocket should put (ID 0) in their resource fork.
They should always set bit 0 (kISpAppResFlag_UsesInputSprocket) and set bit 1
(kISpAppResFlag_UsesISpInit) if they use the high level API (ie they call
ISpInit, ISpConfig, etc... in other words they have a needs list). The rest of
the bits and reserved fields should be set to 0.
A new ISpElementKind has been added: kISpElementKind_Delta which specifies
a Fixed point number of inches moved. InputSprocket Mouse and
InputSprocket Kensington now register elements of this kind in the low level.
The high level (through ISpConfigure) supports axis as well as delta kinds.
This kind is very useful if you want to control a cursor.
A new definition of ISpNeed can be used by defining USE_OLD_ISPNEED_STRUCT to
0.
The first reserved field (a short) was changed to two UInt8s: playerNum and
group. Use playerNum to tell the driver some needs are related to a particular
player (on the same machine). The SprocketInvaders source code will be reved to
use this field. Group is used to group items together, such as a look up, look
down need (assuming you can't use an axis). You should also group items
together
that have the same effect, but are 'tuned' button, axis, and delta versions.
The
current ISp drivers do not use this hinting, yet. Some new definitions for the
ISpNeedFlagBits have been added. If you use the new definition, make sure you
check your code for cases where you were initializing the struct. You now may
be misaligned, and many compilers will NOT generate a warning.
High Level Release Notes:
InputSprocket needs a 640x480 display (or larger) in order for its dialog to
work.
If you are asking DrawSprocket for a smaller display size than that you should
switch out before calling InputSprocket.
Information about how to get saved sets ('setl' Resources) to work is below
under the InputSprocket 1.0 Release Notes
AbsoluteTime and UnsignedWide are in the latest types.h (ETO #20 or later).
/*typedef UnsignedWide AbsoluteTime; struct UnsignedWide {UInt32 hi;UInt32
lo;};*/
InputSprocket Mouse supplies pseudo-buttons in the high level for modifier
keys in combination with mouse clicks. You will have at least four buttons
(where some may actually be command/shift/control/option-click on
one-button mice) for any mouse device. This should make it straightforward
to port games which expect a two button mouse: use ISp with delta and
button needs -- and dont worry about what type of device the user has.
Changes from 1.1
-----------------
- InputSprocket Speech added back to distribution (crashing bug fixed)
- InputSprocket Gravis supports Blackhawk and uses new UI (new save set format)
- InputSprocket Thrustmaster uses new UI (new save set format)
- InputSprocket Joy completely revised, renamed InputSprocket CH, now supports
multiple devices seperately and supports up to 8 buttons and 4 hats per device
(new save set format)
- InputSprocket Kensington added, supports kensington devices regardless
of their software
- InputSprocket Sidewinder 3D Pro added, supports Microsoft Sidewinder joystick
- InputSprocket AppleJack added, supports Pippin/AppleJack controller
- InputSprocket Keyboard supports modifier keys in conjunction with a normal
key
(now either Escape or Cmd-Q are valid for kISpElementLabel_Btn_PauseResume)
- Device and element strings have been reviewed, and some have been changed
- ISpConfigure saves and restores the port.
- A new function: ISpTimeToMicroseconds has been added.
- There are some new bits defined for ISpNeedFlagBits.
- Some new element labels have been added.
- Old saved sets for devices other than mouse and keyboard do not work
Incomplete list of devices input sprocket supports
--------------------------------------------------
- Thrustmaster FCS, Thrustmaster WCS, Thrustmaster RCS
- Gravis Gamepad, Gravis Firebird, Gravis Mousestick II, Gravis Blackhawk
- CH Jetstick, CH Flightstick Pro, CH Pro Pedals, CH Pedals, CH F16
Fighterstick, CH Gamepad, CH Pro Throttle
- Kensington TurboMouse 4.0, TurboMouse 5.0, Thinking Mouse,
Kensington Mouse, CoStar Stringray trackball
- Microsoft SideWinder 3D Pro
- AppleJack/ Pippin Controller
- Speech Recognition
- Keyboard
- traditional Apple 'id handler 1' mouse and 100% compatable mice
- modern 'id handler 4' mice including Logitech Trackman Marble (see the
technote "Space Aliens Ate My Mouse")
Known Problems in 1.2
---------------------
- Kensington Mouse-in-a-box reports two buttons (only the first one works)
- ALPS GlidePoint does not appear if ALPS software is installed (appears w/o
ALPS software)
- Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button
Power') is installed (appears as 1 button mouse w/o Mouse Systems software)
- CH Trackball PRO does not appear
- Thrustmaster software generates keyDowns if so configured with ThrustWare
(fix
is to configure all buttons to do nothing in ThrustWare)
- Machines based on the Tanzania motherboard (Motorola StarMax, APS MPower,
Apple PowerMacintosh 4400) will always show an extra Mouse device for the
PS/2 mouse regardless whether one is plugged in (even though the 4400 has
no PS/2 ports, the phantom ADB devices for them are still created). The
PS/2 mouse only reports one button.
- When a Sidewinder 3D Pro stick is connected, an extra mouse device is shown
which is active when the 'mouse/joystick' switch is switched to 'mouse'.
- It is unstable to have multiple applications use InputSprocket
simultaneously. If your application can be suspended and uses InputSprocket
you should use ISpShutdown and ISpStartup so that InputSprocket is off while
you are in the background. This is a bug (since 1.0) and will be fixed
in the next version. If you are a user you can work around this problem
by not running more than one InputSprocket application at the same time.
- When debugging, you may need to deactivate the Mouse and Keyboard drivers in
order to be able to interact with your debugger.
InputSprocket 1.1
Release Notes
-----------------
General Release Notes:
We recommend that if you are using input sprocket version greater than 1.02
that
you no longer support any third party joystick APIs.
You must not support those APIs at the same time as you have InputSprocket
devices enabled.
High Level Release Notes:
If you are using InputSprocket via the high level (ISpConfigure and ISpInit and
so on). We recommend that you only use the axis and button data types and
build
the controls that you need out of those types. This will get you the best
support. Many of the drivers are going to only primarily emulate those
datatypes.
Known Problems in 1.1
---------------------
- Kensington Trackball does not appear if Kensington software is installed
(appears w/o Kensington software)
- ALPS GlidePoint does not appear if ALPS software is installed (appears w/o
ALPS software)
- Mouse Systems Mouse does not appear if Mouse Systems software ('3-Button
Power') is installed (appears as 1 button mouse w/o Mouse Systems software)
- CoStar Stingray Trackball does not appear if CoStar software ('Stingray') is
installed (appears w/o CoStar software)
- CH Trackball PRO does not appear
- Thrustmaster software generates keyDowns if so configured with ThrustWare
(fix
is to configure all buttons to do nothing in ThrustWare)
Changes from 1.02
-----------------
- new APIs (ISpStartup, ISpShutdown, ISpTickle, ISpDevices_ActivateClass,
ISpDevices_DeactivateClass)
- some general ui improvements in both appearance and performance have been
made
- new driver InputSprocket Joy (supports some features of JoyManager devices --
ie mainly CH products)
- new driver InputSprocket Thrustmaster (supports FCS, WCS, RCS)
- new driver InputSprocket Gravis (supports MouseStick, Firebird, GamePad)
- new driver InputSprocket Speech (you must activate explicitly and requires
ISpTickle be called)
- InputSprocket Mouse changed to have new UI and is implemented via ADBMgr
directly instead of a CursorDeviceMgr Patch
- InputSprocket Keyboard has been slightly changed if there is only one page
- driver function to plot icons has been changed (faster)
- bug when you select a 0 length name to save a set has been fixed
- bug involving choosing monitor has been fixed (might chose something other
than the main monitor randomly)
- CH Flightstick, CH Gamepad, CH Jetstick and MacEnjoy no longer generate a
mouse device
- a crashing bug involving multiple applications using input sprocket
simultaniously has been fixed
- a very small memory leak involving ISpConfigure has been fixed
- DONT_USE_OLD_INPUT_SPROCKET_LABELS changed to USE_OLD_INPUT_SPROCKET_LABELS
in
InputSprocket.h
- a bug where InputSprocket Keyboard and InputSprocket Mouse called InitGraf
has
been fixed
InputSprocket Speech Notes
--------------------------
- you must call ISpTickle in order for InputSprocket Speech to work
- you must call ISpDevices_ActivateClass(kISpDeviceClass_SpeechRecognition) to
turn InputSprocket Speech on
- requires SpeechRecognition extension 1.5.1 (PlainTalk 1.5)
InputSprocket Joy Notes
-----------------------
- supports all JoyManager devices as a single input sprocket device.
- UI may show popups for controls the device does not have
- JoySimpleData based
- only supports the trigger and three additional buttons
- digital pointing devices (ex. CH Gamepad's pad) are treated as a pair of axis
not a POV Hat
InputSprocket 1.02
Release Notes
-----------------
There is a new InputSprocket.h that has new versions of the names for the
labels
as well as additional labels.
The following bugs were fixed in the 1.01 or the 1.02 releases.
- keyboard ui now generates better names than Min/Max for axis if ElementLabel
is useful
- various problems with alignment and growing of dialog were fixed
- flickering with icons in thrustmaster and mouse fixed
- stub library included in this release with file type 'stub'
- axis flipping check box now works again for the mouse driver
- ISpDevices_Extract functions no work when an exact count is passed to them
- Icon plotting is more robust.
- The OK button is no longer hilited when the keyboard is active.
- InputSprocket will now unload the drivers when the last fragment is unloaded
- InputSprocket no longer leaks memory when you quit in the suspended state
- when there are no devices to configure and ISpConfigure is called it will
display a warning instead of doing nothing
- ISpSuspend no longer leaks 10,000 bytes every call
The following bugs are known:
-There is an incompatability with the mouse driver and the Kensignton trackball
software that causes no mice devices to appear.
-There is a incompatability with the Kensington trackball that causes an extra
mouse device to appear when the hardware is installed and the software is not
installed.
InputSprocket 1.0
Release Notes
-----------------
Please report all bugs to sprockets@adr.apple.com!
Release Components
------------------
InputSprocket Release Notes - this file
InputSprocket.h - the header file to compile with
InputSprocketLib - release version of the library
InputSprocketDebugLib - debugging version of the library
InputSprocketStubLib - version of the library to link to
InputSprocket Keyboard - keyboard plug-in
InputSprocket Mouse - mouse plug-in
InputSprocketTest - test program
InputSprocketTest.µ - Metrowerks 8 project to build test
InputSprocketTest Sources - sources for test program
Place InputSprocket Keyboard, InputSprocket Mouse and InputSprocketLib or
InputSprocketDebugLib in the Extensions folder. Place InputSprocket.h in
your development environment's C Headers folder. Place InputSprocketStubLib
in your development environment's Libraries folder.
WARNING: don't place both the debugging and non-debugging versions of the
library in the search path or you will not be sure which version you will be
using.
Dependencies
------------
InputSprocket requires the latest Universal Headers -- version 2.1.2 or later.
You can find them on E.T.O. #20, the MacOS SDK CD-ROMs, Apple's web-site, or
a number of other locations. If you have a problem with the "AbsoluteTime"
type usage, then you aren't using the latest Types.h file.
Compatability with Prereleases
------------------------------
InputSprocket 1.0 is not compatible with any of the pre-release versions of
InputSprocket. You should throw out all DR versions.
Changes to 'setl' Resource
--------------------------
The format for the set list resource ('setl') was changed at the last minute.
A resedit TMPL resource is automatically installed in the preference file and
the format is as follows:
-- header --
Version (4 bytes) The current version is now 2.
Count (4 bytes)
-- each entry --
name (64 bytes) A pascal string
set length (4 bytes) The length of the set
device class (4 bytes) The device class of the device
device identifier (4 bytes) The device identifier of the device
flags (4 bytes) Same flags as in the header
reserved1 (4 bytes) Reserved by apple set to zero.
reserved2 (4 bytes) Reserved by apple set to zero.
reserved3 (4 bytes) Reserved by apple set to zero.
set resource id (2 bytes) The resource id of the set.
reserved4 (2 bytes) Reserved by apple set to zero.
Special Considerations
----------------------
- Your game should use the Escape key to pause and resume play. The
element that corresponds to the Escape key is labelled
ISpElementLabel_Start. If your game uses virtual elements then the
first button need that is labelled ISpElementLabel_Start is auto-
configured to the Escape key, and the user can't change this in
the ISpConfigure dialog.
- Your game may provide default and optional configurations for the
keyboard, the mouse and any other devices. This is done by including
'setl' and 'tset' resources a resource file, such as the application's,
that is open when ISpInit and ISpConfigure are called. Since the
format of the 'tset' resource is determined by the device, it is
easiest to use the configuration dialog to establish the desired
configurations then copy them from the Preferences file into your
resource file.
1. Remove the InputSprocket Preferences file from the Preferences
folder.
2. Run your game, and invoke the ISpConfigure dialog.
3. Configure and save as many sets as you like for any and all
devices.
4. Quit.
5. Use ResEdit to move the 'setl' and 'tset' resources to your
resource file.
6. Edit the 'setl' resource using the 'TMPL' supplied in
InputSprocketSimpleTest.rsrc.
7. Change the flags field to $00000002 for the default entry for
a given device or $00000004 for any other entry for that
device.
8. Again remove the InputSprocket Preferences file from the
Preferences folder so you can test with a clean slate.
9. Rebuild your game and try out your new configurations.